PATH
PATH
MacOS X Server Release Notes Copyright \xa9 1998 by Apple Computer, Inc. All Rights Reserved.
Note: The paper that shipped as the Scripting release note in DR2 has been revised for 1.0 and made part of the Tasks and Concepts documentation. This Scripting, Document, and Undo design paper can now be found in Documentation/Developer/YellowBox/TasksAndConcepts/ProgrammingTopics/AppDesign in the /System folder on Rhapsody and in the Apple root folder on Windows.
Rhapsody 1.0 is the first version to support AppleScript-able Yellow Box applications. The Scripting support in 1.0 should be considered a Beta release. The are known limitations, bugs, and some unimplemented features. This document attempts to provide some information about what is still missing or broken.
This section lists major areas of functionality that are not yet present in 1.0.
Intel/Windows support: The scripting code will work only on PowerPC hardware running Rhapsody 1.0. Rhapsody Intel and Yellow Box for Windows are not yet supported. Yellow Box for Windows will be supported in a future release. The frameworks and headers are available on Rhapsody Intel and on Yellow Box for Windows. You should be able to compile and link applications that link against the Scripting and AppKitScripting frameworks on all platforms, but the Scripting support will only actually work on PPC.
Recording: Recordability is not yet implemented.
Invoking Scripts from Yellow Applications: The ability for a yellow application to send script commands or whole scripts to another yellow application is not yet supported.
Apple Event Manager API: The yellow Apple Event Manager API is not exposed in Rhapsody 1.0. This means that yellow applications that want to use AppleEvents for something other than Scripting currently cannot. It also means that there is no way, at this time, to define your own descriptor types or to define new mappings between yellow classes and unknown descriptor types.
Targetting yellow apps on other hosts: The standard "on machine" and "in zone" syntax of AppleScript does not work for yellow applications currently. We will provide integration with the standard AppleScript syntax in a later release. In the meantime, there is another way to script yellow applications on remote machines. You just specify the hostname as part of the application name after a semicolon. For example tell application "TextEdit;fnord" allows scripting the TextEdit application running on the host fnord. For security considerations, remote scripting is not allowed by default. You can enable remote scripting of applications by using the NSAllowsRemoteAppleEvents default. defaults write NSGlobalDomain NSAllowsRemoteAppleEvents YES will turn on remote scriptability for all applications. You can also turn it on for specific applications by using an application domain (for example: defaults write TextEdit NSAllowsRemoteAppleEvents YES)
This section lists known bugs and other problems in the current release.
Problem: The Get command does not support the "as" argument.
Description: The Get command is unaware of and unable to handle the "as" parameter which allows the scripter to request the data to be returned as a particular type. This means that the result of the Get command will always be whatever type is the default type for the objects that are the result.
Workaround: None really. You must make do with the data type that is the default.
Problem: The Move command's default implementation is very fragile.
Description: If you want your classes to support the Move command robustly, you will probably need to implement your own support for it. The current default implementation has certain limitations. These limitations are most visible in situations where multiple keys of an object refer to the same set of objects (either by providing different subsets, or carving up the data along different boundaries). For instance, Sketch's DrawDocument class defines the keys graphics, rectangles, circles, lines, etc... These keys all refer to the same set of objects (the graphics) but subsetted in different ways. The Move command can be confused by this. The Text suite defines keys such as characters, words, paragraphs, etc... These keys all refer to the same text, just split up in different ways. This also can confuse the default Move implementation.
Workaround: Make your container classes handle the Move command explicitly themselves and take such special situations into account.
Problem: The Get Class Info and Get Command Info events are not supported.
Description: These two Core suite AppleEvents are currently not handled by the Scripting framework.
Workaround: None.
Problem: The Get Data Size event is not currently supported.
Description: This Core suite AppleEvent is currently not handled by the Scripting framework.
Workaround: None.
Problem: Mechanism for translating between AEDescs and yellow objects is not public.
Description: Because the Apple Event Manager APIs are not public, there was no way to expose the ability to define new translation between AEDescs and yellow objects. This means that the only AppleScript data-types supported by the Scripting system currently are the ones built into the frameworks.
Workaround: None.
Problem: The current implementation of the Text suite has performance problems and correctness problems.
Description: The Text suite is mostly supported, but it currently has some serious limitations. The main one is performance. There are several areas of the current implementation that are known to be totally inadequate performance-wise. Also, certain commands (especially Move, but including others as well) either won't work at all, or won't work as well as they should.
The text suite, since it is implemented entirely within the Scripting system, will be able to be fixed without your application ever having to change or be recompiled. A future release should address the performance and correctness problems with the current implementation.
In the meantime, your application should still expose NSTextStorage objects in its container hierarchy where it makes sense.
For now, we recommend avoiding working with large amounts of text through scripts.
Workaround: None.
Problem: Selection class not defined.
Description: The Core suite's Selection class is not currently defined in yellow. It should still be possible for applications to expose selections. Your Document class, for instance, can export a "selectedGraphics" key if it wants to.
Workaround: Just expose your selection in your own way.
Problem: File class not defined.
Description: The Core suite's File class is not currently defined in yellow. Special awareness of the File class has been built in to handle "open file" and "print file" type commands, but these are the only cases where the File class can currently be used. Classes that expose "file" type stuff, like the "path" property of a Document object just expose these paths as strings, currently.
Workaround: You can use path strings or if you really needed to, define and implement your own File class.
Problem: Quit command not supported.
Description: The Core suite's Quit command is not supported. (Neither is automatic launching of yellow scriptable apps from ScriptEditor.)
Workaround: It would be possible to define such a command in your app's suite, but it is recommended that this be avoided unless it is absolutely necessary.
Problem: Open and Print commands do not support list arguments.
Description: The Core suite's Open and Print commands do not handle arguments that are lists. You must open or print things one at a time for now.
Workaround: Use AppleScripts looping constructs to loop through your list of files and open/print them one by one.
Problem: "the last ..." does not work.
Description: Using the AppleScript syntax "last" to identify the last object in an element currently does not work. Specifying a negative index does not work either.
Workaround: Use positive indices.
Problem: The Clone (Duplicate) command claims the "to" argument is required and does not return a result.
Description: According to the spec the "to" argument should be optional (the new objects should be inserted right after the originals if it is omitted). Also, the result of the command should be references to the new objects. Neither of these things is true of yellow scripting today.
Workaround: None.
Problem: There is no way to specify a "default property" or "default specifier".
Description: As an example of what this means, TextEdit's document class has a "text" element but it does not have "characters", "words", etc... It certainly seems desirable to be able to say "word 7 of the front document" but it turns out you must say "word 7 of the text of the front document". It would be nice if TextEdit's document class could advertise that it's "default" property was "text" so that if an object specifier whose container was a document could not be evaluated properly, it could attempt to evaluate within the default "text" container. Similarly, an application's default should be "front document".
Workaround: None. A future release will provide a mechanism for this.
Problem: The scripting terminologies for Sketch and TextEdit are not as complete or flexible as they ought to be.
Description: Not everything these apps do can be done through scripting yet. Also, the terminologies are somewhat more rigid in their expectations than they should be.
Workaround: It is certainly possible to make your own apps have better terminologies than these two sample applications.
Problem: AETE generation does not distinguish between different types of number.
Description: Regardless of whether a property of a class or an argument to a command is supposed to be an integer, a floating point value, a boolean value, a MacOS style 4-letter code, or any other type of number, the AETE generated by a yellow application will always say it is an "integer".
Workaround: None.
Problem: There is no way for ScriptEditor to find a yellow app in order to open its dictionary.
Description: Because ScriptEditor uses a file-system Open dialog to ask what app's dictionary to open, it doesn't see yellow applications.
Workaround: For the standard suites and the TextEdit and Sketch suites, see below. There is a workaround if you want to see your own app's suites: If you set the default NSScriptingInsertTestMenu to YES (in your app domain, or the global domain) then an extra menu will be inserted into scriptable apps. The first menu item should be ignored. The second item will dump the AETE data for the app into a file at ~/newstuff/<AppName>.aete. Make sure that the directory ~/newstuff exists first. This file can be ftp'd to MacOS and embedded into a Mac application as an aete resource (using ResEdit or Resourcerer). Then you can open that application's dictionary in ScriptEditor.
This section contains definitions of the Standard and Text suites as wqell as the TextEdit and Sketch suites in a format similar to the Terminology Dictionaries that ScriptEditor presents.
close: Close an object.
close reference -- the object for the command
[saving yes/no/ask] -- Specifies whether changes should be saved before closing.
[saving in string] -- The file in which to save the object.
count: Return the number of elements of a particular class within an object.
count reference -- the object for the command
Result: anything -- the reply for the command
delete: Delete an object.
delete reference -- the object for the command
duplicate: Copy object(s) and put the copies at a new location.
duplicate reference -- the object for the command
to anything -- The location for the new object(s).
exists: Verify if an object exists.
exists reference -- the object for the command
Result: anything -- the reply for the command
get: Get the data for an object.
get reference -- the object for the command
Result: anything -- the reply for the command
make: Make a new object.
make
[with data anything] -- The initial data for the object.
new class -- The class of the new object.
[with properties record] -- The initial values for properties of the object.
at anything -- The location at which to insert the object.
Result: reference -- the reply for the command
move: Move object(s) to a new location.
move reference -- the object for the command
to anything -- The new location for the object(s).
open: Open an object.
open anything -- The only supported form of this command is: open file "filePath"
print: Print an object.
print anything -- print file "filePath" is supported. Printing of document or window objects is also supported.
save: Save an object.
save reference -- the object for the command
[as string] -- The file type in which to save the data.
[in string] -- The file in which to save the object.
set: Set an object's data.
set reference -- the object for the command
to anything -- The new value.
Abstract object: Abstract object provides a base class for scripting classes. It is never used directly.
Properties:
class type [r/o] -- The class of the object.
application: An application's top level scripting object.
Plural form:
applications
Elements:
documents
windows
Properties:
name string [r/o] -- The name of the application.
version integer [r/o] -- The version of the application.
frontmost boolean [r/o] -- Is this the frontmost (active) application?
class type [r/o] -- The class of the object.
document: A document.
Plural form:
documents
Properties:
modified boolean [r/o] -- Has the document been modified since the last save?
path string -- The document's path.
name string -- The document's name.
class type [r/o] -- The class of the object.
window: A window.
Plural form:
windows
Elements:
document
Properties:
is visible boolean -- Whether the window is currently visible.
is miniaturizable boolean [r/o] -- Whether the window can be miniaturized.
index integer -- The index of the window in the back-to-front window ordering.
has close box boolean [r/o] -- Whether the window has a close box.
is zoomable boolean [r/o] -- Whether the window can be zoomed.
has title bar boolean [r/o] -- Whether the window has a title bar.
is zoomed boolean -- Whether the window is currently zoomed.
is floating boolean [r/o] -- Whether the window floats.
is miniaturized boolean -- Whether the window is currently miniaturized.
is resizable boolean [r/o] -- Whether the window can be resized.
name string -- The full title of the window.
is running modal boolean [r/o] -- Whether the window is the application's current modal window.
class type [r/o] -- The class of the object.
color: A color.
Plural form:
colors
Properties:
class type [r/o] -- The class of the object.
text: Rich (styled) text
Elements:
text
attribute runs
paragraphs
words
characters
Properties:
size float -- The size in points of the first character.
color color -- The color of the first character.
font string -- The name of the font of the first character.
class type [r/o] -- The class of the object.
attribute run: This subdivides the text into chunks that all have the same attributes.
Plural form:
attribute runs
Elements:
text
attribute runs
paragraphs
words
characters
Properties:
size float -- The size in points of the first character.
color color -- The color of the first character.
font string -- The name of the font of the first character.
class type [r/o] -- The class of the object.
paragraph: This subdivides the text into paragraphs.
Plural form:
paragraphs
Elements:
text
attribute runs
paragraphs
words
characters
Properties:
size float -- The size in points of the first character.
color color -- The color of the first character.
font string -- The name of the font of the first character.
class type [r/o] -- The class of the object.
word: This subdivides the text into words.
Plural form:
words
Elements:
text
attribute runs
paragraphs
words
characters
Properties:
size float -- The size in points of the first character.
color color -- The color of the first character.
font string -- The name of the font of the first character.
class type [r/o] -- The class of the object.
character: This subdivides the text into characters.
Plural form:
characters
Elements:
text
attribute runs
paragraphs
words
characters
Properties:
size float -- The size in points of the first character.
color color -- The color of the first character.
font string -- The name of the font of the first character.
class type [r/o] -- The class of the object.
text attachment: Represents an inline text attachment. This class is used mainly for make commands.
Elements:
text
attribute runs
paragraphs
words
characters
Properties:
file name string -- The path to the file for the attachment
size float -- The size in points of the first character.
color color -- The color of the first character.
font string -- The name of the font of the first character.
class type [r/o] -- The class of the object.
document: A TextEdit document.
Plural form:
documents
Elements:
text
Properties:
modified boolean [r/o] -- Has the document been modified since the last save?
path string -- The document's path.
name string -- The document's name.
class type [r/o] -- The class of the object.
application: TextEdit's top level scripting object.
Plural form:
applications
Elements:
documents
windows
Properties:
name string [r/o] -- The name of the application.
version integer [r/o] -- The version of the application.
frontmost boolean [r/o] -- Is this the frontmost (active) application?
class type [r/o] -- The class of the object.
application: Sketch's top level scripting object.
Plural form:
applications
Elements:
documents
windows
Properties:
name string [r/o] -- The name of the application.
version integer [r/o] -- The version of the application.
frontmost boolean [r/o] -- Is this the frontmost (active) application?
class type [r/o] -- The class of the object.
document: A Sketch document.
Plural form:
documents
Elements:
graphics
rectangles
circles
lines
images
text areas
Properties:
modified boolean [r/o] -- Has the document been modified since the last save?
path string -- The document's path.
name string -- The document's name.
class type [r/o] -- The class of the object.
graphic: A graphic. This abstract class represents the individual shapes in a Sketch document. There are subclasses for each specific type of graphic.
Plural form:
graphics
Properties:
x position float -- The x coordinate of the graphic's bounding rectangle.
y position float -- The y coordinate of the graphic's bounding rectangle.
width float -- The width of the graphic's bounding rectangle.
height float -- The height of the graphic's bounding rectangle.
fill color color -- The fill color.
stroke color color -- The stroke color.
stroke thickness float -- The thickness of the stroke.
class type [r/o] -- The class of the object.
rectangle: A rectangle graphic.
Plural form:
rectangles
Properties:
x position float -- The x coordinate of the graphic's bounding rectangle.
y position float -- The y coordinate of the graphic's bounding rectangle.
width float -- The width of the graphic's bounding rectangle.
height float -- The height of the graphic's bounding rectangle.
fill color color -- The fill color.
stroke color color -- The stroke color.
stroke thickness float -- The thickness of the stroke.
class type [r/o] -- The class of the object.
circle: A circle graphic.
Plural form:
circles
Properties:
x position float -- The x coordinate of the graphic's bounding rectangle.
y position float -- The y coordinate of the graphic's bounding rectangle.
width float -- The width of the graphic's bounding rectangle.
height float -- The height of the graphic's bounding rectangle.
fill color color -- The fill color.
stroke color color -- The stroke color.
stroke thickness float -- The thickness of the stroke.
class type [r/o] -- The class of the object.
line: A line graphic.
Plural form:
lines
Properties:
x position float -- The x coordinate of the graphic's bounding rectangle.
y position float -- The y coordinate of the graphic's bounding rectangle.
width float -- The width of the graphic's bounding rectangle.
height float -- The height of the graphic's bounding rectangle.
fill color color -- The fill color.
stroke color color -- The stroke color.
stroke thickness float -- The thickness of the stroke.
class type [r/o] -- The class of the object.
image: an image
Plural form:
images
Properties:
imagefile string -- The graphic file to use for the contents of the image. This attribute should only be used for setting.
x position float -- The x coordinate of the graphic's bounding rectangle.
y position float -- The y coordinate of the graphic's bounding rectangle.
width float -- The width of the graphic's bounding rectangle.
height float -- The height of the graphic's bounding rectangle.
fill color color -- The fill color.
stroke color color -- The stroke color.
stroke thickness float -- The thickness of the stroke.
class type [r/o] -- The class of the object.
text area: A text graphic.
Plural form:
text areas
Elements:
text contents
Properties:
x position float -- The x coordinate of the graphic's bounding rectangle.
y position float -- The y coordinate of the graphic's bounding rectangle.
width float -- The width of the graphic's bounding rectangle.
height float -- The height of the graphic's bounding rectangle.
fill color color -- The fill color.
stroke color color -- The stroke color.
stroke thickness float -- The thickness of the stroke.
class type [r/o] -- The class of the object.
text contents: The textual contents of a text area graphic.
Elements:
text
attribute runs
paragraphs
words
characters
Properties:
size float -- The size in points of the first character.
color color -- The color of the first character.
font string -- The name of the font of the first character.
class type [r/o] -- The class of the object.